package expertise.titan.dao;

import com.thinkaurelius.titan.core.TitanTransaction;
import com.thinkaurelius.titan.diskstorage.StorageException;

/**
 * This interface defines the fundamental operations for a data access object
 * using the Titan API in our system.
 * 
 * @author bdgould
 * 
 * @param <T>
 *            The type of schema object being accessed
 */
public interface TitanDao<T> {

    /**
     * Persist a node into the graph. Uses the provided {@link TitanTransaction}
     * .
     * 
     * @param transaction
     *            The transaction that will roll up the actions taken
     * @param instance
     *            The instance of the node to persist
     * @throws StorageException
     *             If there is an issue persisting the node
     */
    void create(final TitanTransaction transaction, final T instance) throws StorageException;

    /**
     * Read a node from the graph with the provided name.
     * 
     * @param transaction
     *            The transaction to use on the read
     * @param name
     *            The name of the node to read (the type of node is determined
     *            by the used DAO)
     * @return The node from the graph (or null if it doesn't exist)
     * @throws StorageException
     *             If there is an issue interfacing with the graph
     */
    T read(final TitanTransaction transaction, final String name) throws StorageException;

    /**
     * Update the provided node.
     * 
     * @param transaction
     *            The transaction to use during the update
     * @param updatedInstance
     *            The instance as it WILL be after the update
     * @param name
     *            The name of the node to update
     * @throws StorageException
     *             If there is an issue updating the node
     */
    void update(final TitanTransaction transaction, final T updatedInstance, final String name) throws StorageException;

    /**
     * Delete the specified node from the graph.
     * 
     * @param transaction
     *            The transaction to use to delete the node
     * @param instance
     *            The instance of the node to delete on the graph
     * @throws StorageException
     *             If there is an issue interfacing with the graph
     */
    void delete(final TitanTransaction transaction, final T instance) throws StorageException;

}
